Select URL API ile reklam öğelerini dönüşümlü yayınlama

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Kullanıcının sitelerde gördüğü reklam öğesini belirlemek için Shared Storage'dan yararlanmak üzere Select URL API'yi kullanın.

Reklamverenler veya içerik üreticiler, bir kampanyaya farklı içerik rotasyonu stratejileri uygulamak ve etkililiği artırmak için içerikleri veya reklam öğelerini döndürmek isteyebilir. Select URL API, farklı sitelerde sıralı rotasyon ve eşit olarak dağıtılmış rotasyon gibi farklı rotasyon stratejileri çalıştırmak için kullanılabilir.

Select URL API reklam öğesi rotasyonu sayesinde, kullanıcıların farklı sitelerde gördüğü reklam öğesini belirlemek için reklam öğesi kimliği, görüntüleme sayısı ve kullanıcı etkileşimi gibi verileri depolayabilirsiniz.

Temel API ve seçimin işleyiş şekli hakkında daha fazla bilgi için Select URL API belgelerini inceleyin.

Reklam öğesi rotasyonunu deneyin

Reklam öğesi rotasyonunu denemek için Select URL API ve Shared Storage'ın etkinleştirildiğinden emin olun:

• chrome://settings/content/siteData bölümünde Allow sites to save data on your device veya Delete data sites have saved to your device when you close all windows'yi seçin.
• chrome://settings/adPrivacy/sites bölümünde Site-suggested ads'u seçin.

Bu dokümandaki kod örneklerinin canlı sürümünü görmek için Shared Storage canlı demomuzu deneyin.

Kod örnekleri içeren demo

Bu örnekte:

• creative-rotation.js, döndürülecek içeriği tanımlayan üçüncü taraf komut dosyasıdır. Bu komut dosyasında, seçilecek ve gösterilecek sonraki içeriği belirleyen veriler de (bu örnekte ağırlıklar gibi) bulunur. Yayıncı sayfası bu komut dosyasını yürütür. Bu komut dosyası, depolama alanındaki mevcut verilere ve seçilecek URL'lerin listesine göre hangi içeriğin gösterileceğini belirlemek için Shared Storage iş parçacığını çağırır.

• creative-rotation-worklet.js, üçüncü tarafın rotasyon stratejisini arayan, bir sonraki yayınlanacak içeriği hesaplayan ve bu içeriği döndüren paylaşılan depolama alanı işleyicisidir.

Demo'nun işleyiş şekli

1. Kullanıcı yayıncı sayfasını ziyaret ettiğinde sayfa, üçüncü tarafın creative-rotation.js komut dosyasını yükler. Reklam öğesi rotasyonu komut dosyası, ortak depolama alanı iş parçacığının yüklenmesi ve çalıştırılmasından sorumludur. Komut dosyası, iş parçası çağrısına aralarından seçim yapılabilecek URL'lerin listesini sağlar.
2. Çalışma alanında, paylaşılan depolama alanı henüz başlatılmamışsa depolama alanı, ilk reklam öğesi rotasyon stratejisi ve reklam öğesi dizini ile başlatılır. Bu demoda kullanılan ilk rotasyon stratejisi sıralı stratejidir.
3. İş akışı, rotasyon modunu paylaşılan depolama alanından okur ve sonraki reklamın dizini döndürür. Sıralı rotasyon modunda ise paylaşılan depolama alanındaki reklam öğesi dizini, sonraki çağrı için kullanılacak yeni değerle de güncellenir.İş parçası, selectURL çağrısı yapılırken kullanılan resolveToConfig değerine göre bir FencedFrameConfig veya opak URN nesnesi döndürür.
4. Reklam öğesi rotasyonu komut dosyası, seçili reklamı korumalı çerçevede veya iFrame'de gösterir. Döndürülen türlerle ilgili ayrıntılar için reklam oluşturma dokümanlarını inceleyin.
5. Kullanıcı döndürme modunu değiştirdiğinde ortak depolama alanı iş parçası, ortak depolama alanında depolanan reklam öğesi döndürme modu değerini günceller.
6. Yayıncı sayfası yeniden yüklenirken 1-4 arasındaki adımlar tekrarlanır. Böylece, seçilen rotasyon stratejisine göre görüntülenecek bir sonraki reklam seçilebilir.

Kod örnekleri

Aşağıda, creative-rotation.js ve creative-rotation-worklet.js için kod örnekleri verilmiştir.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Ekran görüntüleriyle açıklamalı kılavuz

1. Select URL API ve Shared Storage'ı kullanarak reklam öğesi rotasyonuna erişmek için https://shared-storage-demo.web.app/ adresine gidin. "Reklam öğesi rotasyonu" demosunu seçin.

2. Demoyu "Yayıncı A" olarak keşfetmeyi seçin. https://shared-storage-demo-publisher-a.web.app/creative-rotation adresine yönlendirilirsiniz. Sayfa, Select URL API aracılığıyla erişilen Shared Storage'a kaydedilen reklam öğesi rotasyonu verilerine göre numaralandırılmış içeriği yükler. Reklam öğesi rotasyonu için demo modları sıralı, eşit dağıtım ve ağırlıklı dağıtımdır. İş parçası, iframe'de görünen içeriği seçmek için mantığı yürütür. Aşağıdaki resimde yayıncı sayfası gösterilmektedir.

   
   

3. Shared Storage'da depolanan öğeleri görüntülemek için Chrome DevTools'da Uygulama -> Shared Storage'a gidin. Paylaşılan depolama alanı için iki giriş oluşturulur. https://shared-storage-demo-publisher-a.web.app kaynağı için boş depolama alanı kullanılabilir. Bu, söz konusu kaynağa özel depolama alanı içerir ve yayıncının ortak depolama alanına yazması gerekmediğinden demo için boş kalır. Demo için daha sonra bu sayfayı ziyaret ettiğinizde B yayıncısı için benzer bir depolama alanının oluşturulacağını unutmayın.

   
   

4. https://shared-storage-demo-content-producer.web.app kaynağı için başka bir Shared Storage girişi oluşturulur. Bu, yayıncı sayfasına yerleştirilmiş üçüncü taraf iframe'in depolama alanıdır. Bu depolama alanı, reklam öğesi seçimini koordine etmek için mevcut iki yayıncı arasında veri paylaşmak için kullanılır. Bu paylaşılan depolama alanı, iki anahtar/değer çifti kaydederek gösterilen reklam öğesi ve rotasyon stratejisi hakkında bilgi kaydetmek için kullanılır. Demoda kullanılan ilk anahtar creative-rotation-index'tir. Bu anahtarın değeri, sıralı moddaki geçerli reklam öğesi dizinidir. İkinci anahtar, kullanılan rotasyon stratejisini belirten creative-rotation-mode anahtarıdır.

   
   

5. Sıralı moddayken sayfayı yenilemek, 1, 2, 3, 1, ... sırasına göre bir sonraki reklam öğesinin gösterilmesine neden olur. creative-rotation-index anahtarının değeri, sıralı moddayken gösterilen reklam öğesinin dizine göre değişir.

   
   

6. Kontrol düğmelerini kullanarak reklam öğesi rotasyon modunu değiştirmek, ilgili stratejideki creative-rotation-mode anahtarının değerini günceller. Bu değer, iFrame'de gösterilecek sonraki reklam öğesini seçmek için worklet kodu tarafından kullanılır. creative-rotation-index için kaydedilen değerin, sıralı dışındaki rotasyon modlarında değişmediğini unutmayın.

   
   

7. https://shared-storage-demo-publisher-b.web.app/creative-rotation adresindeki "Yayıncı B" sayfasına gidin. Sıralı modda gösterilen reklam öğesi, "Yayıncı A"nın URL'si ziyaret edildiğinde gösterilen sıradaki reklam öğesi olmalıdır. İçerik üreticinin Paylaşılan Depolama Alanını incelediğinizde hem "Yayıncı A" hem de "Yayıncı B"nin aynı depolama alanını paylaştığını ve gösterilecek bir sonraki reklam öğesini ve kullanılacak rotasyon stratejisini seçmek için buradaki ayarları kullandığını görebilirsiniz.

   
   

8. "Yayıncı B"nin paylaşılan depolama alanı, "Yayıncı A"nın paylaşılan depolama alanına benzer şekilde boştur.

   
   

   Kullanım alanları

   Seçili URL API'si için kullanılabilen tüm kullanım alanlarını bu bölümde bulabilirsiniz. Geri bildirim aldıkça ve yeni test örnekleri keşfettikçe örnekler eklemeye devam edeceğiz.

   • Reklam öğelerini döndürme: Kullanıcıların farklı sitelerde gördüğü reklam öğesini belirlemek için reklam öğesi kimliği ve kullanıcı etkileşimi gibi verileri depolayın.
   • Reklam öğelerini sıklıklarına göre seçme: Kullanıcıların farklı sitelerde gördüğü reklam öğelerini belirlemek için görüntüleme sayısı verilerini kullanın.
   • A/B testi çalıştırma: Bir kullanıcıyı deneme grubuna atayabilir ve ardından bu grubu, siteler arası erişilebilmesi için Shared Storage'da saklayabilirsiniz.
   • Tanınmış müşteriler için deneyimi özelleştirme: Kullanıcının kayıt durumuna veya diğer kullanıcı durumlarına göre özel içerikler ve harekete geçirici mesajlar paylaşın.

Etkileşim kurma ve geri bildirim paylaşma

Seçili URL API teklifinin aktif olarak tartışıldığını ve geliştirildiğini ve değişiklik yapılabileceğini unutmayın.

Seçili URL API'si hakkındaki düşüncelerinizi öğrenmek isteriz.

• Teklif: Ayrıntılı teklifi inceleyin.
• Tartışma: Soru sormak ve analizlerinizi paylaşmak için devam eden tartışmaya katılın.

Gelişmeleri takip edin

• Posta Listesi: Seçili URL ve Paylaşılan Depolama API'leri ile ilgili en son güncellemeler ve duyurular için posta listemize abone olun.

Yardıma mı ihtiyacınız var?

• Geliştirici desteği: Diğer geliştiricilerle bağlantı kurun ve Privacy Sandbox Geliştirici Desteği deposunda sorularınızın yanıtlarını alın.